Description

Motivation

Hook providers need the ability to distinguish between expected errors (like validation failures that the model should adjust for and retry) and unexpected errors (like assertion failures or configuration errors that should fail the task immediately). Currently, AfterToolCallEvent.exception is always None for @tool-decorated functions because the decorator catches all exceptions and converts them to error results before the executor can see them. This forces all tool errors to be returned to the model, even when propagating the exception would be more appropriate.

Resolves: #1565

Public API Changes

ToolResultEvent now accepts an optional exception parameter, and AfterToolCallEvent.exception is populated for decorated tools:

# Before: exception is always None for decorated tools
class MyHook(HookProvider):
    def register_hooks(self, registry, **kwargs):
        registry.add_callback(AfterToolCallEvent, self._check)

    def _check(self, event: AfterToolCallEvent):
        # event.exception is always None for @tool functions
        # even when the tool raised an exception
        pass

# After: exception is available for inspection
class PropagateUnexpectedExceptions(HookProvider):
    def __init__(self, allowed_exceptions=(ValueError,)):
        self.allowed_exceptions = allowed_exceptions

    def register_hooks(self, registry, **kwargs):
        registry.add_callback(AfterToolCallEvent, self._check)

    def _check(self, event: AfterToolCallEvent):
        if event.exception is None:
            return
        if isinstance(event.exception, self.allowed_exceptions):
            return  # Let model retry
        raise event.exception  # Propagate unexpected errors

The error result is still returned to the model by default; hooks must explicitly re-raise if they want to propagate.

Use Cases

• Fail-fast on unexpected errors: Propagate AssertionError, ConfigurationError, etc. instead of letting the model retry futilely
• Error classification: Log or handle different exception types differently based on their class
• Selective retry: Allow ValueError to return to the model while propagating other exceptions

Related Issues

#1565

Documentation PR

strands-agents/docs#482

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.